Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@hyperfleet/components/adapter/framework/adapter-status-contract.md`:
- Line 678: The example request path uses PUT /api/v1/clusters/{id}/statuses
which doesn't match the documented base URL contract
/api/hyperfleet/{version}/clusters/{clusterId}/statuses; update the example at
the PUT example to follow the base URL shape (include the /api/hyperfleet/
prefix and {version} segment and use {clusterId} as the path parameter) so the
example and the documented contract (the base URL string
/api/hyperfleet/{version}/clusters/{clusterId}/statuses) are consistent.
- Around line 96-98: Update the table of contents and any lingering references
titled "POST Request" and "Always Use POST" to reflect the new PUT-based
contract by renaming those TOC entries and internal anchors to "PUT Request
(Upsert ClusterStatus)" (and any variant text) so they match the actual section
heading; also update the two other occurrences mentioned (around the same
document's later instances) so all links/anchors and cross-references point to
the PUT section rather than POST. Ensure header IDs/anchors (if present) and any
inline references to the old POST wording are changed to the new PUT wording to
keep the TOC, links, and section titles consistent.

In `@hyperfleet/components/api-service/hard-delete-design.md`:
- Around line 97-103: The sequence diagrams mix POST and PUT for adapter status
updates during deletion; update every occurrence of status-update messages in
this deletion flow so they use PUT (e.g., change any "POST
/clusters/{id}/adapter_statuses" or "POST /nodepools/{id}/adapter_statuses"
messages later in the file to "PUT ...") to preserve deletion semantics; ensure
the existing payload semantics (Finalized=True, Reconciled=False and any adapter
condition details) remain unchanged and that CLAdapter, API, and NPAdapter
arrows reflect PUT consistently throughout the deletion sequence.
- Around line 51-57: The documentation uses two different endpoint paths (`PUT
/adapter_statuses` in this file vs the standardized `PUT .../statuses` used
elsewhere), creating an ambiguous API contract; update the text in
hard-delete-design.md to use the canonical `PUT .../statuses` everywhere
(replace occurrences of `PUT /adapter_statuses` and similar variants) so it
matches the rest of the PR and HyperFleet status-reporting conventions, and run
a quick grep/scan for any remaining `adapter_statuses` mentions to ensure
consistency with the standardized status endpoint naming.

In `@hyperfleet/docs/status-guide.md`:
- Around line 133-143: The guide inconsistently documents status reporting
(mixing POST/PATCH with PUT); standardize the contract to always use PUT for
adapter status reports by replacing all POST/PATCH references with PUT for the
endpoint `/v1/clusters/{clusterId}/statuses`, update the Table of Contents and
every section (including "Adapter Status Reporting Flow" and all example
request/response blocks and cURL/code snippets) to show PUT and the API's upsert
behavior, ensure the explanatory note under "Adapter Action: PUT Status Report"
clearly states the API performs upsert, and run a project-wide search for
occurrences of `/v1/clusters/*/statuses` or "status report" to confirm no stray
POST/PATCH guidance remains.
- Around line 1703-1706: The example for "Scenario 1" contradicts the documented
adapter request contract: it shows a full ClusterStatus payload (generation +
adapter_statuses) while the text says an adapter PUTs only its adapter-specific
status; update the doc to make the contract consistent by either (A) replacing
the sample request body for PUT /v1/clusters/cls-123/statuses with the
adapter-only status payload shape used elsewhere (the per-adapter status
object/fields) and mention that the server will create the ClusterStatus
resource, or (B) explicitly state that the first reporting adapter must send the
full ClusterStatus (including generation and adapter_statuses) and keep the
sample body but also align other examples to that contract; locate and update
the example body and the surrounding explanatory sentence mentioning
ClusterStatus and adapter_statuses to reflect the chosen contract (use the same
adapter-only payload shape or the full ClusterStatus shape consistently).

---

Outside diff comments:
In `@hyperfleet/components/adapter/framework/adapter-integration-tests.md`:
- Around line 98-108: The docs were changed to describe PUT
/clusters/{clusterId}/statuses but the mock server in
test/integration/testutil/mock_api_server.go still registers and handles POST
for "/clusters/{id}/statuses"; update the mock to register a handler for PUT (or
both PUT and POST) that performs the same store/upsert logic as the existing
POST handler (where the handler function that currently stores status and
returns success is registered), or revert the documentation change until the
mock's route registration is updated so the test spec and implementation match.

In `@hyperfleet/components/api-service/api-service.md`:
- Around line 57-69: The Dependencies section still says "Adapters POST status
updates" while all /statuses endpoints (e.g.
/api/hyperfleet/v1/clusters/{id}/statuses and
/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses) are now defined as
PUT; update that prose to state that adapters PUT status updates (or "Adapters
send status updates via PUT to the /statuses endpoints") so the contract matches
the endpoint table, and ensure any other occurrences of "POST status updates"
(e.g., the referenced Dependencies paragraph) are changed to "PUT" to keep the
document consistent.
- Around line 57-69: The docs list the status-report endpoints as PUT but the
authoritative OpenAPI/artifacts in openshift-hyperfleet/hyperfleet-api still
define them as POST, causing contract drift; reconcile by choosing the correct
HTTP method and making both places consistent: update the markdown lines for
`/api/hyperfleet/v1/clusters/{id}/statuses` and
`/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` to match the
OpenAPI (or update the OpenAPI to use PUT if that is the intended change), then
run the API docs generation/tests and update any operationId/consumer code that
depends on the method so clients remain correct. Ensure the chosen method is
reflected in the OpenAPI spec, generated API docs, and this api-service.md.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@hyperfleet/components/adapter/framework/adapter-design-decisions.md`:
- Line 181: Update the table of contents entry that still reads "Adapters POST
Status Updates" so it matches the section heading "Adapters PUT Status Updates":
change the TOC text to "Adapters PUT Status Updates" and update the anchor link
(if present) to match the heading slug for "Adapters PUT Status Updates" so the
TOC text and link both point to the correct section. Ensure the anchor/slug
formatting matches how other headings are generated in this document.

In `@hyperfleet/components/adapter/framework/adapter-flow-diagrams.md`:
- Around line 527-532: The diagram text still describes adapters using POST and
idempotency rules; update that section to reflect PUT semantics to match the
diagram (replace mentions of POST with PUT and adjust idempotency wording
accordingly), ensuring actors like Sub_Adapter, Res_Adapter and Sentinel are
described as using PUT for status updates and resource cleanup and that the
idempotency contract language matches PUT behavior (safe to retry/replace
existing state) so the document no longer contains conflicting guidance.

In `@hyperfleet/components/adapter/framework/adapter-frame-design.md`:
- Line 775: The document contains mixed POST/PUT guidance; update all references
to use PUT-only semantics: change the phrase "via POST requests" in the "Status
Reporter Utilities" section to "via PUT requests", update any other occurrences
that mention POST (including the example/request snippets under the "PUT status
payload to HyperFleet API endpoint" header and the content currently at lines
~975-977) so headers, prose, and sample HTTP verbs/curl examples consistently
use PUT, and ensure any code examples, function names or endpoints that indicate
POST are corrected to PUT semantics (look for the "Status Reporter Utilities"
section and the "PUT status payload to HyperFleet API endpoint" heading to
locate the places to fix).

In `@hyperfleet/components/adapter/framework/adapter-metrics.md`:
- Line 225: The example metric hyperfleet_adapter_api_requests_total shows
method="PUT" but the allowed-method enum in the metric label definition omits
PUT; update the label definition for the method enum (the allowed-method list
used for the method label in the metric documentation/instrumentation guidance)
to include "PUT" alongside existing methods so the documentation and example for
hyperfleet_adapter_api_requests_total are consistent.

In `@hyperfleet/components/adapter/framework/adapter-status-contract.md`:
- Around line 640-642: The endpoint path in the example uses "/api/{{
.hyperfleetApiVersion }}/clusters/{{ .clusterId }}/statuses" which does not
match this doc’s contract that expects
"/api/hyperfleet/{hyperfleetApiVersion}/..."; update the endpoint template (the
endpoint value using .hyperfleetApiBaseUrl and .hyperfleetApiVersion) to include
the "hyperfleet" segment so it reads "/api/hyperfleet/{{ .hyperfleetApiVersion
}}/clusters/{{ .clusterId }}/statuses" (or alternatively change the contract at
its declaration to remove the "hyperfleet" segment) so both the endpoint in this
file and the contract at the earlier declaration are identical.

In `@hyperfleet/README.md`:
- Line 146: The README now documents PUT for the /clusters/{id}/statuses
endpoint but other repos use POST; update the hyperfleet documentation and mocks
so the HTTP verb is consistent across repos: choose the agreed verb (PUT or
POST), then update hyperfleet/README.md entry ("Reports status → ...") to match
and update hyperfleet-api spec/examples and hyperfleet-adapter mock/integration
tests to use the same verb for /clusters/{id}/statuses (or explicitly add a
compatibility note in README stating both verbs are supported and describe
behavior); ensure test fixtures and API examples in hyperfleet-api and
hyperfleet-adapter reference the exact path /clusters/{id}/statuses and reflect
the chosen verb.

---

Outside diff comments:
In `@hyperfleet/components/api-service/api-service.md`:
- Around line 57-69: The Dependencies table still refers to adapters sending
status updates via POST which is stale—update that entry to reflect the new PUT
contract used elsewhere (e.g., change the "adapters POST status updates" wording
to "adapters PUT status updates" and ensure endpoints listed match the PUT
endpoints `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` and
`/api/hyperfleet/v1/clusters/{id}/statuses`); search for the phrase "adapters
POST status updates" (and the duplicate at lines referenced) and replace it with
the correct PUT description and endpoint references so the document consistently
reflects the PUT migration.
- Around line 57-69: The API doc change flips the HTTP verb for the nodepool
status endpoint from POST to PUT causing cross-repo contract drift; revert the
method for `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` back to
POST (or else coordinate and update all clients/servers to accept PUT), and add
a compatibility note in the docs indicating the change and required upgrades in
`hyperfleet-api` and `hyperfleet-adapter` so consumers are not broken; ensure
the same treatment is applied to the cluster-level
`/api/hyperfleet/v1/clusters/{id}/statuses` entry if intended.

---

Duplicate comments:
In `@hyperfleet/components/adapter/framework/adapter-status-contract.md`:
- Line 678: The example request path currently shows the incorrect short form
"PUT /api/v1/clusters/cls-123/statuses"; update the example to use the
documented base URL contract by replacing that path with the full contract form
"{hyperfleetApiBaseUrl}/api/hyperfleet/{hyperfleetApiVersion}/clusters/{clusterId}/statuses"
(e.g., "PUT
{hyperfleetApiBaseUrl}/api/hyperfleet/{hyperfleetApiVersion}/clusters/cls-123/statuses")
so the example matches the contract defined earlier and avoids client
implementation errors.
- Around line 96-98: The table of contents still references "POST" for the
adapter upsert sections even though the body headings were changed to "PUT";
update the TOC entries (the ones currently pointing to the upsert/adapter-status
sections referenced near the original Line 16 and Line 51 and also occurrences
around 772-774) so their labels and anchor targets use "PUT" and match the exact
heading text/anchor of the corresponding "PUT Request (Upsert ClusterStatus)"
section(s); ensure anchor slugs are consistent with the heading text (or update
headings to match TOC if you prefer) so links work and labels read "PUT Request"
instead of "POST".

In `@hyperfleet/docs/status-guide.md`:
- Line 19: The TOC entry for "Reporting Status: Always PUT" still links to the
old anchor "#reporting-status-always-post"; update the anchor target in the TOC
so the link matches the new section id by replacing
"#reporting-status-always-post" with "#reporting-status-always-put" for the
"[Reporting Status: Always PUT]" TOC item to restore correct navigation.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@hyperfleet/README.md`:
- Line 146: The README shows a mismatch for the HTTP verb on the
/clusters/{id}/statuses endpoint (docs changed to PUT but hyperfleet-api still
documents POST while hyperfleet-adapter tests expect PUT); resolve the contract
by choosing and enforcing a single behavior: if PUT is the contract, update all
hyperfleet-api docs and examples (README.md, docs/api-resources.md,
docs/api-operator-guide.md, docs/hyperfleet-api.http) to use PUT for
/clusters/{id}/statuses; if POST is still required, revert the architecture
change and update hyperfleet-adapter tests/mocks to POST; if both are supported,
add explicit compatibility notes and semantics for /clusters/{id}/statuses
across hyperfleet-api, hyperfleet-adapter, and architecture docs so tests,
examples, and mocks align with the agreed verb.

---

Outside diff comments:
In `@hyperfleet/components/api-service/api-service.md`:
- Around line 57-70: The documentation still describes adapters POSTing status
updates in the Dependencies section while the endpoint tables use PUT; update
the Dependencies text to state that adapters must use HTTP PUT to
/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses (and similarly for
/clusters/{id}/statuses) so the file consistently mandates PUT-only status
updates; edit the Dependencies paragraph mentioning "POST" to "PUT" and adjust
any example requests or wording to reflect PUT semantics.
- Around line 57-70: Docs inconsistency: the node pool status upsert endpoint is
documented as PUT here
(`/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` using PUT) but
other repo docs/examples (openshift-hyperfleet/hyperfleet-api) still show POST;
update all API docs/spec examples to use PUT for the nodepool status upsert so
the contract is consistent—search for and replace usages of POST for the
`/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` and
`/api/hyperfleet/v1/clusters/{id}/statuses` endpoints in the API repo, example
clients, and OpenAPI/Swagger specs to reflect PUT and ensure examples and tests
use the PUT verb.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@hyperfleet/components/adapter/adapter-versioning.md`:
- Around line 236-237: Documentation mismatch: update the hyperfleet-api docs
(docs/hyperfleet-api.http, docs/api-resources.md, docs/api-operator-guide.md) to
reflect that cluster and nodepool status endpoints use HTTP PUT (implemented in
plugins/clusters/plugin.go routed via http.MethodPut to the .Create handler)
instead of POST; search for references to "POST" for these status endpoints and
replace or annotate them to show PUT as the correct verb, update any example
requests/samples to use PUT, and ensure text describing the endpoint behavior
references the .Create handler and PUT semantics.

In `@hyperfleet/docs/status-guide.md`:
- Around line 233-235: Update the PUT /v1/clusters/{clusterId}/statuses request
contract in status-guide.md to remove any adapter-owned timestamp fields
(notably condition.last_transition_time) from example request payloads and text,
and explicitly state that last_transition_time is API-managed per
adapter-status-contract.md; ensure the section for lines 239-279 is similarly
unified so all examples and prose instruct adapters to omit API-controlled
timestamps and only supply allowed fields, referencing the
adapter-status-contract.md rule for clarity.

---

Outside diff comments:
In `@hyperfleet/components/api-service/api-service.md`:
- Line 225: The dependency table row currently reads "Adapters | POST status
updates to this API" but the document's status-reporting endpoints use PUT;
update that table entry to "Adapters | PUT status updates to this API" (replace
POST with PUT) so the "Adapters" row matches the status reporting definition
(ensure any references to status-reporting method names or the status endpoint
in this file are consistent with the PUT contract and validate the change
against HyperFleet architecture standards).
- Around line 154-155: The README claims "OpenAPI-first" and a single source of
truth, but the cross-repo docs in openshift-hyperfleet/hyperfleet-api still
advertise POST status upserts instead of the PUT contract; either update the
other repo's API docs/examples to match the PUT semantics (replace POST upsert
examples with PUT-based examples and ensure generated clients/handlers reflect
the OpenAPI spec), or add an explicit compatibility note here in api-service.md
(near the "OpenAPI-first" paragraph) stating that legacy POST upserts are still
documented in openshift-hyperfleet/hyperfleet-api and will be deprecated,
referencing the PUT contract and where consumers should look for the canonical
OpenAPI spec.

---

Duplicate comments:
In `@hyperfleet/components/adapter/framework/adapter-status-contract.md`:
- Around line 640-641: Update the example endpoint strings so they follow the
canonical base URL contract `/api/hyperfleet/{hyperfleetApiVersion}/...`;
specifically change the endpoint value used in the examples (the lines defining
endpoint: "{{ .hyperfleetApiBaseUrl }}/api/{{ .hyperfleetApiVersion
}}/clusters/{{ .clusterId }}/statuses" and the other example that currently uses
`/api/v1/...`) to include the literal "hyperfleet" segment (i.e.,
`/api/hyperfleet/{{ .hyperfleetApiVersion }}/...`) so both examples match the
contract referenced at Line 71.

In `@hyperfleet/docs/status-guide.md`:
- Around line 219-223: Update the "Why this pattern?" section to remove the
stale "No GET/POST/PATCH logic needed" phrasing and explicitly reference the
"always PUT" contract: replace that bullet with a concise statement like "Single
HTTP verb: always PUT" (or similar) and adjust surrounding bullets to avoid
implying GET/POST/PATCH logic; ensure the section text (heading "Why this
pattern?" and the bullets) consistently reflects the always-PUT migration
guidance and HyperFleet architecture standards.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@hyperfleet/components/adapter/framework/adapter-flow-diagrams.md`:
- Line 131: The sequence diagram still shows GET /statuses and PATCH
/statuses/{statusId} branches alongside the new A->>API: PUT /statuses line;
update the diagram to remove the GET+PATCH fallback branches and consolidate
into a single PUT-only upsert path so the flow documents the PUT upsert contract
consistently (replace or remove the GET /statuses and PATCH /statuses/{statusId}
fragments and ensure only the A->>API: PUT /statuses step and its resulting
state transitions — e.g., Applied/Available/Health outcomes — remain), and make
the same change for the other occurrences referenced (the entries around the
same pattern at the other noted locations).

In `@hyperfleet/components/api-service/api-service.md`:
- Line 57: The API docs for the endpoint
`/api/hyperfleet/v1/clusters/{id}/statuses` currently show PUT while the
canonical specs in openshift-hyperfleet/hyperfleet-api still publish POST,
causing contract drift; update the
hyperfleet/components/api-service/api-service.md to match the source-of-truth in
openshift-hyperfleet/hyperfleet-api (or add an explicit migration note with the
source-of-truth referenced) by either changing the HTTP method entry from PUT
back to POST for `/api/hyperfleet/v1/clusters/{id}/statuses` (and the same for
the other occurrence at line 69) or adding a clear header indicating the docs
are transitional and that openshift-hyperfleet/hyperfleet-api is authoritative.